Clean Node - Efficient Node Modules Cleanup Tool

A high-performance Node.js utility designed to efficiently find and delete node_modules directories across your system, helping you reclaim valuable disk space with minimal system impact.

🎯 What is Clean Node?

Clean Node is a command-line tool that scans your file system for node_modules directories and safely removes them. It's particularly useful for developers who work with multiple Node.js projects and want to free up disk space without manually hunting down each node_modules folder.

Why Use Clean Node?

🚀 Fast & Efficient: Uses async operations and smart filtering for optimal performance
💾 Disk Space Recovery: Reclaim gigabytes of space from unused dependencies
🛡️ Safe & Smart: Automatically skips system directories and provides confirmation prompts
📊 Detailed Reporting: Shows exactly what was deleted and how much space was freed
⚡ Zero Dependencies: Pure Node.js - no external dependencies required

🚀 Quick Start

Installation & Usage

# Quick start - scan and delete node_modules automatically
npx delete-nodes -y

# Or with confirmation prompt
npx delete-nodes

# Scan from a specific directory
npx delete-nodes /path/to/your/projects -y

Local Installation (Alternative)

# Clone the repository
git clone https://github.com/sarowarhosen03/clean-node.git
cd clean-node

# Make it executable
chmod +x index.js

# Run it
./index.js

📖 Detailed Usage Guide

Command Line Options

npx delete-nodes [directory_path] [options]

Arguments:

directory_path (optional): The starting directory to scan. Defaults to your home directory (~)

Options:

-y, --yes: Automatically confirm deletion without prompting
-h, --help: Show help information (coming soon)

Examples:

# Scan home directory with confirmation
npx delete-nodes

# Scan home directory and auto-delete
npx delete-nodes -y

# Scan specific directory with confirmation
npx delete-nodes ~/projects

# Scan specific directory and auto-delete
npx delete-nodes ~/projects -y

Usage Examples

1. Clean Your Entire Home Directory

# This will scan your entire home directory for node_modules
npx delete-nodes

# Auto-delete without confirmation
npx delete-nodes -y

2. Clean Specific Project Directories

# Clean from your projects folder
npx delete-nodes ~/projects

# Clean from a specific project
npx delete-nodes ~/projects/my-app

# Clean from multiple locations (run multiple times)
npx delete-nodes ~/work-projects
npx delete-nodes ~/personal-projects

# Auto-delete from specific directories
npx delete-nodes ~/projects -y

3. Test on a Small Directory First

# Test the tool on a small directory before running on your entire system
npx delete-nodes ~/test-directory

# Test with auto-delete
npx delete-nodes ~/test-directory -y

4. Using npm Scripts (Local Installation)

# Standard usage
npm start

# Development/testing mode
npm run dev

# Test mode
npm test

🔧 How It Works

Scanning Process

Directory Traversal: Recursively scans directories starting from the specified path
Smart Filtering: Automatically skips:
- Hidden directories (starting with .)
- System directories (Desktop, Documents, Downloads, etc.)
- Version control directories (.git, .svn)
- IDE directories (.vscode, .idea)
- Already found node_modules directories
Node Modules Detection: Identifies directories named node_modules
Path Collection: Gathers all found node_modules paths

Deletion Process

Confirmation: Shows all found directories and asks for user confirmation
Progress Tracking: Displays real-time progress during deletion
Safe Deletion: Uses fs.rm() with recursive and force options
Error Handling: Continues operation even if some deletions fail
Reporting: Shows final results including space freed

⚡ Performance Features

Asynchronous Operations

Uses fs.promises for non-blocking file system operations
Allows other processes to run concurrently during scanning
Prevents UI freezing during long operations

Smart Directory Skipping

// Automatically skips these directories
const SKIP_DIRS = new Set([
    'Desktop', 'Documents', 'Downloads', 'Music', 
    'Pictures', 'Public', 'Templates', 'Videos'
]);

// Skips these patterns
const IGNORE_PATTERNS = [
    /^\./,        // Hidden files/directories
    /^\.git$/,    // Git directory
    /^\.vscode$/, // VS Code settings
    /^\.idea$/,   // IntelliJ settings
];

Node Modules Optimization

Stops scanning inside node_modules: Once a node_modules directory is found, it's added to the deletion list and scanning stops inside it
Prevents infinite recursion: Maximum depth limit prevents excessive recursion
Memory efficient: Processes directories without storing everything in memory

📊 Output Examples

Successful Scan and Deletion (with confirmation)

Scanning for node_modules directories starting from: /home/user
This may take a while for large directory trees...

Scan completed in 1250ms
Found 15 node_modules directories

Directories to be deleted:
1. /home/user/project1/node_modules
2. /home/user/project2/node_modules
3. /home/user/old-project/node_modules
4. /home/user/work/project-a/node_modules
5. /home/user/work/project-b/node_modules
...

Do you want to delete these node_modules directories? (y/n): y

Starting deletion process...
Deleting 15/15: old-project/node_modules

✅ Successfully deleted 15 node_modules directories
📦 Freed approximately 2.34 GB of disk space
⏱️  Deletion completed in 3200ms

Auto-Confirmation Mode (-y flag)

Scanning for node_modules directories starting from: /home/user
⚠️  Auto-confirmation enabled (-y flag)
This may take a while for large directory trees...

Scan completed in 1250ms
Found 15 node_modules directories

Directories to be deleted:
1. /home/user/project1/node_modules
2. /home/user/project2/node_modules
3. /home/user/old-project/node_modules
...

✅ Auto-confirming deletion (use without -y flag for manual confirmation)

Starting deletion process...
Deleting 15/15: old-project/node_modules

✅ Successfully deleted 15 node_modules directories
📦 Freed approximately 2.34 GB of disk space
⏱️  Deletion completed in 3200ms

No Node Modules Found

Scanning for node_modules directories starting from: /home/user
This may take a while for large directory trees...

Scan completed in 450ms
No node_modules directories found.

Operation Cancelled

Found 8 node_modules directories

Directories to be deleted:
1. /home/user/project1/node_modules
2. /home/user/project2/node_modules
...

Do you want to delete these node_modules directories? (y/n): n
❌ Operation cancelled.

🛡️ Safety Features

Confirmation System

Always asks for user confirmation before deletion
Shows exactly which directories will be deleted
Allows cancellation at any time

System Protection

Automatically skips important system directories
Handles permission errors gracefully
Continues operation even if some directories fail

Error Handling

// Graceful error handling for common issues
try {
    await fs.rm(nodeModulesPath, { recursive: true, force: true });
} catch (error) {
    console.warn(`Warning: Could not delete ${nodeModulesPath}: ${error.message}`);
}

Graceful Interruption

Handles Ctrl+C (SIGINT) gracefully
Provides clear feedback when interrupted
Exits cleanly without leaving processes hanging

🔧 Development

Project Structure

clean-node/
├── index.js          # Main application file
├── package.json      # Project configuration
└── README.md         # This documentation

Available Scripts

# Start the application
npm start

# Run tests
npm test

# Development mode (test on specific directory)
npm run dev

Requirements

Node.js: >= 14.0.0
File System: Read/write permissions for target directories
Operating System: Linux, macOS, or Windows (with Node.js)

🚨 Important Notes

Before Using

Backup Important Data: While the tool is safe, always ensure you can regenerate your dependencies
Check Dependencies: Make sure you have package.json files for projects you want to keep
Test First: Run on a small directory first to understand the behavior

What Gets Deleted

Only directories named exactly node_modules
Only the node_modules directory itself (not the parent project)
All contents within node_modules directories

What's Protected

Your source code and project files
package.json and package-lock.json files
System directories and hidden files
Version control directories

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/clean-node.git
cd clean-node

# Install dependencies (if any are added in the future)
npm install

# Make your changes
# Test thoroughly
npm test

# Submit a pull request

Contribution Guidelines

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and test thoroughly
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Areas for Improvement

Performance optimizations
Additional filtering options
GUI interface
Integration with package managers
Support for other dependency directories (vendor, lib, etc.)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

Use at your own risk! This tool permanently deletes node_modules directories. While it's designed to be safe, always ensure you can regenerate your dependencies before using this tool. The authors are not responsible for any data loss.

📞 Support

If you encounter any issues or have questions:

Check the documentation above
Search existing issues on GitHub
Create a new issue with detailed information about your problem
Include your operating system and Node.js version

Happy cleaning! 🧹✨

Delete Nodes